[PM-26542] Add listing items functionality with session-based authentication with environment variable support for API key login #492

fer · 2025-10-06T14:10:49Z

🎟️ Tracking

https://bitwarden.atlassian.net/browse/PM-26542

📔 Objective

Implements session-based authentication for the Rust Bitwarden CLI, enabling stateless command execution similar to the Node.js CLI. Users can now authenticate once with bw login api-key and reuse the session for subsequent commands.

Added environment variable support (BW_CLIENTID, BW_CLIENTSECRET, BW_PASSWORD) to the bw login api-key command and made it return a base64-encoded session key (like the Node.js CLI, although this one is reaally long) that can be potentially used with --session (or BW_SESSION) for subsequent vault operations.

Session Management

Session Export: Added export_session() to serialize full client state
Session Import: Added import_session() to restore complete authenticated state from session string
Session Format: Base64-encoded JSON containing all crypto keys and OAuth tokens needed for vault operations

Environment Variable Support

Added support for environment variables in bw login api-key:

BW_CLIENTID (or BW_CLIENT_ID): API client ID
BW_CLIENTSECRET (or BW_CLIENT_SECRET): API client secret
BW_PASSWORD: Master password
Environment variables take precedence over interactive prompts

List Command Implementation

Implemented bw list items with filtering options:
- --search: Text search across items
- --folderid: Filter by folder
- --collectionid: Filter by collection
- --organizationid: Filter by organization
- --trash: Show deleted items
Returns decrypted vault items as JSON

Session Usage

The global --session flag and BW_SESSION environment variable now work across all commands, automatically restoring client state before execution.

Usage Example

# Set credentials via environment variables
export BW_CLIENTID="user.xxx"
export BW_CLIENTSECRET="xxx"
export BW_PASSWORD="xxx"

# Login and capture session
SESSION=$(bw login api-key)

# Use session for subsequent commands
bw list items --session "$SESSION"

# Or via environment variable
export BW_SESSION="$SESSION"
bw list items

⏰ Reminders before review

Contributor guidelines followed
All formatters and local linters executed and passed
Written new unit and / or integration tests where applicable
Protected functional changes with optionality (feature flags)
Used internationalization (i18n) for all UI strings
CI builds passed
Communicated to DevOps any deployment requirements
Updated any necessary documentation (Confluence, contributing docs) or informed the documentation
team

🦮 Reviewer guidelines

👍 (:+1:) or similar for great changes
📝 (:memo:) or ℹ️ (:information_source:) for notes or general info
❓ (:question:) for questions
🤔 (:thinking:) or 💭 (:thought_balloon:) for more open inquiry that's not quite a confirmed
issue and could potentially benefit from discussion
🎨 (:art:) for suggestions / improvements
❌ (:x:) or ⚠️ (:warning:) for more significant problems or concerns needing attention
🌱 (:seedling:) or ♻️ (:recycle:) for future improvements or indications of technical debt
⛏ (:pick:) for minor or nitpick changes

…turn session token to reuse

bitwarden-bot · 2025-10-06T14:12:34Z

Thank you for your contribution! We've added this to our internal tracking system for review.
ID: PM-26542
Link: https://bitwarden.atlassian.net/browse/PM-26542

Details on our contribution process can be found here: https://contributing.bitwarden.com/contributing/pull-requests/community-pr-process.

codecov · 2025-10-06T14:30:30Z

Codecov Report

❌ Patch coverage is 0% with 200 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.57%. Comparing base (ae9b8b5) to head (398c69d).

Files with missing lines	Patch %	Lines
crates/bw/src/vault/list.rs	0.00%	71 Missing ⚠️
crates/bitwarden-core/src/client/internal.rs	0.00%	59 Missing ⚠️
crates/bw/src/main.rs	0.00%	27 Missing ⚠️
crates/bw/src/auth/login.rs	0.00%	21 Missing ⚠️
crates/bitwarden-cli/src/lib.rs	0.00%	16 Missing ⚠️
crates/bw/src/auth/mod.rs	0.00%	4 Missing ⚠️
crates/bw/src/command.rs	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #492      +/-   ##
==========================================
- Coverage   78.10%   77.57%   -0.54%     
==========================================
  Files         283      284       +1     
  Lines       27628    27818     +190     
==========================================
  Hits        21579    21579              
- Misses       6049     6239     +190

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Apply cargo fmt to fix import ordering and line wrapping to comply with CI style checks.

Separate external crate imports from internal crate imports with blank lines to comply with nightly rustfmt group_imports feature used in CI.

addisonbeck

This looks good to me. Will re-approve if you decide to rename text_or_env_prompt, but that's not blocking.

crates/bitwarden-cli/src/lib.rs

github-actions · 2025-10-16T19:54:03Z

Checkmarx One – Scan Summary & Details – 605789bf-c365-45ff-aab7-d841638071ef

Great job! No new security vulnerabilities introduced in this pull request

sonarqubecloud · 2025-10-16T19:54:53Z

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

nick-livefront

Let me know if there is future work slated to flush out the implementation of the vault related items. If list is just being used as an easy implementation to test against, the changes are good with me.

crates/bw/src/vault/list.rs

Add unimplemented archive feature to match Node.js CLI: - Add `archive` command with todo!() placeholder - Add `--archived` flag to list command - Update ListOptions struct with archived field Should align with bitwarden/clients#16502 for future implementation.

nick-livefront

Thank you for addressing my feedback!

fer · 2025-10-27T10:48:18Z

This looks good to me. Will re-approve if you decide to rename text_or_env_prompt, but that's not blocking.

Please don't hesitate to propose more changes if needed, happy to help!

crates/bw/src/auth/login.rs

Hinton

Do we need to add this into the core crate? I was imaging we could temporarily add some glue code to the cli expecially since this implementation isn't really compliant to the current cli.

fer · 2025-10-27T14:49:06Z

Do we need to add this into the core crate? I was imaging we could temporarily add some glue code to the cli expecially since this implementation isn't really compliant to the current cli.

@Hinton I do believe it probably should be somewhere else, and agreed that the direct key extraction/injection might violate KM architecture.

Please don't hesitate to point me out on how to refactor this situation. My current idea is to move export/import to bitwarden_crypto (❓) context file and then in internal.rs just simply wrap.

Hinton · 2025-10-28T12:36:48Z

Not sure where you got bitwarden-crypto from. I specifically asked for the cli.

I hacked together bitwarden-labs#1 which ilustrates how we can implement this in the least invasive way possible to other crates.

Additionally after discussions with other people we don't feel comfortable calling this session, because it works in a fundamentally different way from session in the regular cli. Rather than providing an encryption key the session is just a b64 encoded dump of very sensitive data.

To that end, we think renaming login api-key to login temporary-insecure-login api-key and session to temporary-insecure-session will avoid any confusion about this down the road.

read env vars for client id/secret password when using api-key and re…

d1dce55

…turn session token to reuse

fer requested a review from a team as a code owner October 6, 2025 14:10

fer requested a review from addisonbeck October 6, 2025 14:10

fer changed the title ~~read env vars for client id/secret password when using api-key and re…~~ env vars for client id/secret password when using api-key, return SESSION token Oct 6, 2025

bitwarden-bot added needs-qa community-pr and removed needs-qa labels Oct 6, 2025

fer added 3 commits October 6, 2025 21:24

Add session export/import with full crypto state

96a3dc6

Add session import support to CLI

a45722c

Implement list items command with filtering

f79ed34

fer changed the title ~~env vars for client id/secret password when using api-key, return SESSION token~~ Add listing items functionality with session-based authentication with environment variable support for API key login Oct 6, 2025

fer added 2 commits October 6, 2025 22:05

Fix code formatting

6750acd

Apply cargo fmt to fix import ordering and line wrapping to comply with CI style checks.

Fix nightly rustfmt import grouping

a57175e

Separate external crate imports from internal crate imports with blank lines to comply with nightly rustfmt group_imports feature used in CI.

fer changed the title ~~Add listing items functionality with session-based authentication with environment variable support for API key login~~ [PM-26542] Add listing items functionality with session-based authentication with environment variable support for API key login Oct 6, 2025

added basic information to bw's doc

398c69d

addisonbeck previously approved these changes Oct 16, 2025

View reviewed changes

crates/bitwarden-cli/src/lib.rs Outdated Show resolved Hide resolved

rename text_or_env_prompt to resolve_user_input_value

9236ae5

fer dismissed addisonbeck’s stale review via 9236ae5 October 17, 2025 09:36

fer requested review from a team as code owners October 17, 2025 09:36

fer requested review from Patrick-Pimentel-Bitwarden and nick-livefront October 17, 2025 09:36

nick-livefront requested changes Oct 17, 2025

View reviewed changes

crates/bw/src/vault/list.rs Outdated Show resolved Hide resolved

crates/bw/src/vault/list.rs Show resolved Hide resolved

crates/bw/src/vault/list.rs Outdated Show resolved Hide resolved

fer added 2 commits October 17, 2025 19:10

linter

b1ef4e5

refactor: convert list object parameter from String to enum

4886199

fer added 2 commits October 17, 2025 19:59

feat: enhance CLI search to match nodejs implementation

3a42f2b

nick-livefront approved these changes Oct 22, 2025

View reviewed changes

fer closed this Oct 27, 2025

fer reopened this Oct 27, 2025

Patrick-Pimentel-Bitwarden reviewed Oct 27, 2025

View reviewed changes

crates/bw/src/auth/login.rs Show resolved Hide resolved

Hinton reviewed Oct 27, 2025

View reviewed changes

[PM-26542] Add listing items functionality with session-based authentication with environment variable support for API key login #492

Are you sure you want to change the base?

[PM-26542] Add listing items functionality with session-based authentication with environment variable support for API key login #492

Conversation

fer commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🎟️ Tracking

📔 Objective

Session Management

Environment Variable Support

List Command Implementation

Session Usage

Usage Example

⏰ Reminders before review

🦮 Reviewer guidelines

Uh oh!

bitwarden-bot commented Oct 6, 2025

Uh oh!

codecov bot commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

addisonbeck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Oct 16, 2025

Great job! No new security vulnerabilities introduced in this pull request

Uh oh!

sonarqubecloud bot commented Oct 16, 2025

Quality Gate passed

Uh oh!

nick-livefront left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nick-livefront left a comment

Choose a reason for hiding this comment

Uh oh!

fer commented Oct 27, 2025

Uh oh!

Uh oh!

Hinton left a comment

Choose a reason for hiding this comment

Uh oh!

fer commented Oct 27, 2025

Uh oh!

Hinton commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

fer commented Oct 6, 2025 •

edited

Loading

codecov bot commented Oct 6, 2025 •

edited

Loading

Hinton commented Oct 28, 2025 •

edited

Loading